SQL Server Integration Services : The Package Execution Utility (part 2) - Running Packages

Running Packages

The dtexec options are additive. Depending on what you are trying to do, you are able to string one or more options and their values together in the following form:

dtexec /option [value] [/option [value]] ...

To show available options for dtexec, you use '/?' or '/H' or '/Help'. Alternatively, you can see the details for a particular option by using the available options indicator followed by the option name ('/? [option name]). This invokes SQL Server Books online for that particular option. Note that a dash (-) may be substituted for / in this command.

The dtexec package execution options include the following:

• /~CheckF[ile] filespec— This option sets the CheckpointFileName property on the package to the path and file specified in filespec. This file is used when the package restarts.

• /~CheckP[ointing]{on\off}— The value on specifies that a failed package is to be rerun. When the failed package is rerun, the runtime engine uses the checkpoint file to restart the package from the point of failure. The default value is on if the option is declared without a value. Package execution fails if the value is set to on and the checkpoint file cannot be found. If this option is not specified, the value set in the package is retained.

  Note

  Using the /CheckPointing on option of dtexec is equivalent to setting the SaveCheckpoints property of the package to True and the CheckpointUsage property to Always.

  
  

• /~Com[mandFile] filespec— This option specifies that during the command sourcing phase of the utility, the file specified in filespec is opened, and options from the file are read until the EOF is found in the file. filespec is a text file that contains additional dtexec command options. The filespec argument specifies the filename and path of the command file to associate with the execution of the package.

• /~Conf[igFile] filespec— This option specifies a configuration file to extract values from. Using this option, you can set a runtime configuration that differs from the configuration specified for the package at design time.

• /~Conn[ection] id_or_name;connection_string [[;id_or_name;connection_string]...]— This option specifies the specific connection manager name or GUID and the specific connection string to use. This option requires that both parameters be specified.

• /~Cons[oleLog] [[displayoptions];[list_options;src_name_or_guid]...]— This option displays specified log entries to the console during package execution.

  The displayoptions values are N (name), C (computer), O (operator), S (source name), G (source GUID), X (execution GUID), M (message), and T (time start and end).

  One list_options value is I, which specifies the inclusion list. With this value set, only the source names or GUIDs that are specified are logged. The value Esrc_name_or_guid parameter specified for inclusion or exclusion is an event name, a source name, or a source GUID. specifies the exclusion list. With this value set, the source names or GUIDs that are specified are not logged. The

• /~D¥ package_path— This option is used to load a package from the SSIS package store. The package_path argument specifies the relative path of the SSIS package, starting at the root of the SSIS package store, and includes the name of the SSIS package. The /DTS option cannot be used together with the /File or /SQL option.

• /~De[crypt] password— This option provides the decryption password used when you load a package with password encryption.

• /~F[ile]filespec— This option is used to load a package saved at the filesystem level. The filespec argument specifies the path and filename of the package.

• /~L[ogger]classid_orprogid;configstring— This option associates one or more log providers with the execution of an SSIS package. The classid_orprogidconfigstring is the string used to configure the log provider. parameter specifies the log provider and can be specified as a class GUID.

  Following are the available log providers:

  Text file:
   ProgID: DTS.LogProviderTextFile.1
   ClassID: {59B2C6A5-663F-4C20-8863-C83F9B72E2EB}
  SQL Server Profiler:
   ProgID: DTS.LogProviderSQLProfiler.1
   ClassID: {5C0B8D21-E9AA-462E-BA34-30FF5F7A42A1}
  SQL Server:
   ProgID: DTS.LogProviderSQLServer.1
   ClassID: {6AA833A1-E4B2-4431-831B-DE695049DC61}
  Windows Event Log:
   ProgID: DTS.LogProviderEventLog.1
   ClassID: {97634F75-1DC7-4F1F-8A4C-DAF0E13AAA22}
  XML File:
   ProgID: DTS.LogProviderXMLFile.1
   ClassID: {AFED6884-619C-484F-9A09-F42D56E1A7EA}
  

• /~M[axConcurrent] concurrent_executables— This option is used to identify the number of executable files the package can run concurrently. The value specified must be either a non-negative integer or –1. With a value of –1, SSIS allows a maximum number of concurrently running executables equal to the total number of processors on the computer executing the package, plus two.

• /~P[assword] password— This option is used together with the /User option to retrieve the package from SQL Server. If the /Password option is omitted and the /User option is used, a blank password is used.

• /~Rem comment— This option creates a comment on the command prompt or in command files. The comment is a string that must be enclosed in quotation marks, and it must contain no whitespace.

• /~Rep[orting] level [;event_guid_or_name[;event_guid_or_name[...]]— This option identifies what types of messages to report. Available reporting option levels are N (no reporting), E (errors are reported), W (warnings are reported), I (informational messages are reported), C (custom events are reported), DP (progress is reported), and V (verbose reporting; all details of each type). If the /Reporting option is not specified, the default level is E, W, and P. (data flow task events are reported),

• /~Res[tart] {deny | force | ifPossible}— This option enables you to set a new value for the CheckpointUsage property on the package. The possible values are Deny (sets the CheckpointUsage property to DTSCU_NEVER), Force (sets the CheckpointUsage property to DTSCU_ALWAYS), and ifPossible (sets the CheckpointUsage property to DTSCU_IFEXISTS).

• /~Set propertyPath;value— This option overrides the configuration of a variable, property, container, log provider, Foreach enumerator, or connection within a package. When this option is used, /SET changes the propertyPath argument to the value specified. You can specify more than one /SET option at a time.

• /~Ser[ver] server— This option identifies the name of the server from which to retrieve the package. If you do not specify the /Server option, the package execution is attempted against the local server.

• /~SQ[L] package_path— This option is used to load a package stored in SQL Server (in the msdb database).

• /~Su[m]— This option displays the incremental counter that contains the number of rows that will be received by the next package component.

• /~U[ser] user_name— This option identifies the SQL Server user ID needed to retrieve the package.

• /~Va[lidate]— This option is used to complete the validation phase of package execution only. The package is not executed.

• /~VerifyB[uild] major[;minor[;build]]— This option is a verification of the build number of a package against the build numbers specified during the verification phase in the major, minor, and build arguments. If a mismatch occurs, the package does not execute. These values are long integers.

• /~VerifyP[ackageID] packageID— This option verifies the GUID of the package to be executed by comparing it to the value specified in the package_id argument.

• /~VerifyS[igned]— If specified, this option causes the package to fail if the package is not signed.

• /~VerifyV[ersionID] versioned— This option verifies the version GUID of a package to be executed by comparing it to the value specified in the version_id argument during the package validation phase.

• /~W[arnAsError]— This option cause the package to consider a warning as an error. In other words, the package fails if a warning occurs during validation. If no warnings occur during validation and the /Validate option is not specified, the package is executed.

Running Package Examples

To execute an SSIS package saved to SQL Server using Windows authentication, you use the following code:

dtexec /SQL UnleashedPackage1SQL /SER DBARCH-LT2\SQL08DE01

To execute an SSIS package saved to the package store (on the filesystem), you use the following code:

dtexec /DTS "\File System\UnleashedPackage99PS"

To execute an SSIS package saved in the filesystem, you use the following code:

C:> dtexec /FILE "C:\HotCustomerPlus.dtsx"
    /MAXCONCURRENT " -1 " /CHECKPOINTING OFF  /REPORTING EWCDI

Figure 3 shows the command prompt and subsequent execution of the HotCustomersPlus.dtsx SSIS package. Now, the package can be set up for regular batch execution using SQL Agent or any scheduling software.

Figure 3. Command-line execution of an SSIS package.

To execute an SSIS package saved in the filesystem and specify logging options, you use the following code:

C:> dtexec /FILE "C:\HotCustomerPlus.dtsx"
    /l "DTS.LogProviderTextFile;c:\log.txt"

To execute a package that uses Windows authentication and is saved to the default local instance of SQL Server, and to verify the version before it is executed, you use the following code:

dtexec /sq UnleashedPackage1 /verifyv {b399e360-38c5-11c5-99x1-ae62-08002b2b79ef}